"""
协议接口定义
Protocol Interface Definition

定义了IoT设备通信协议的抽象接口
Defines the abstract interface for IoT device communication protocols
"""

from abc import ABC, abstractmethod
from typing import Dict, Any, Optional
from pydantic import BaseModel


class ProtocolInterface(ABC):
    """
    协议接口抽象类
    Abstract base class for device protocols
    
    定义了设备协议处理的标准接口
    Defines the standard interface for device protocol handling
    """
    
    @abstractmethod
    async def parse_request(self, raw_data: Dict[str, Any]) -> Optional[BaseModel]:
        """
        解析请求数据
        Parse request data
        
        Args:
            raw_data (Dict[str, Any]): 原始请求数据 / Raw request data
            
        Returns:
            Optional[BaseModel]: 解析后的数据模型 / Parsed data model
        """
        pass
    
    @abstractmethod
    async def format_response(self, data: Any) -> Dict[str, Any]:
        """
        格式化响应数据
        Format response data
        
        Args:
            data (Any): 响应数据 / Response data
            
        Returns:
            Dict[str, Any]: 格式化后的响应 / Formatted response
        """
        pass
    
    @abstractmethod
    async def validate_request(self, data: Dict[str, Any]) -> bool:
        """
        验证请求数据
        Validate request data
        
        Args:
            data (Dict[str, Any]): 请求数据 / Request data
            
        Returns:
            bool: 验证结果 / Validation result
        """
        pass
    
    @abstractmethod
    def get_protocol_version(self) -> str:
        """
        获取协议版本
        Get protocol version
        
        Returns:
            str: 协议版本 / Protocol version
        """
        pass
    
    @abstractmethod
    def get_supported_actions(self) -> list:
        """
        获取支持的操作类型
        Get supported action types
        
        Returns:
            list: 支持的操作列表 / List of supported actions
        """
        pass